home *** CD-ROM | disk | FTP | other *** search
/ IRIX 6.2 Development Libraries / SGI IRIX 6.2 Development Libraries.iso / dist / complib.idb / usr / share / catman / p_man / cat3 / complib / zhgeqz.z / zhgeqz
Text File  |  1996-03-14  |  7KB  |  199 lines
  1.  
  2.  
  3.  
  4. ZZZZHHHHGGGGEEEEQQQQZZZZ((((3333FFFF))))                                                          ZZZZHHHHGGGGEEEEQQQQZZZZ((((3333FFFF))))
  5.  
  6.  
  7.  
  8. NNNNAAAAMMMMEEEE
  9.      ZHGEQZ - implement a single-shift version of the QZ method for finding
  10.      the generalized eigenvalues w(i)=ALPHA(i)/BETA(i) of the equation   det(
  11.      A - w(i) B ) = 0  If JOB='S', then the pair (A,B) is simultaneously
  12.      reduced to Schur form (i.e., A and B are both upper triangular) by
  13.      applying one unitary tranformation (usually called Q) on the left and
  14.      another (usually called Z) on the right
  15.  
  16. SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS
  17.      SUBROUTINE ZHGEQZ( JOB, COMPQ, COMPZ, N, ILO, IHI, A, LDA, B, LDB, ALPHA,
  18.                         BETA, Q, LDQ, Z, LDZ, WORK, LWORK, RWORK, INFO )
  19.  
  20.          CHARACTER      COMPQ, COMPZ, JOB
  21.  
  22.          INTEGER        IHI, ILO, INFO, LDA, LDB, LDQ, LDZ, LWORK, N
  23.  
  24.          DOUBLE         PRECISION RWORK( * )
  25.  
  26.          COMPLEX*16     A( LDA, * ), ALPHA( * ), B( LDB, * ), BETA( * ), Q(
  27.                         LDQ, * ), WORK( * ), Z( LDZ, * )
  28.  
  29. PPPPUUUURRRRPPPPOOOOSSSSEEEE
  30.      ZHGEQZ implements a single-shift version of the QZ method for finding the
  31.      generalized eigenvalues w(i)=ALPHA(i)/BETA(i) of the equation A are then
  32.      ALPHA(1),...,ALPHA(N), and of B are BETA(1),...,BETA(N).
  33.  
  34.      If JOB='S' and COMPQ and COMPZ are 'V' or 'I', then the unitary
  35.      transformations used to reduce (A,B) are accumulated into the arrays Q
  36.      and Z s.t.:
  37.  
  38.           Q(in) A(in) Z(in)* = Q(out) A(out) Z(out)*
  39.           Q(in) B(in) Z(in)* = Q(out) B(out) Z(out)*
  40.  
  41.      Ref: C.B. Moler & G.W. Stewart, "An Algorithm for Generalized Matrix
  42.           Eigenvalue Problems", SIAM J. Numer. Anal., 10(1973),
  43.           pp. 241--256.
  44.  
  45.  
  46. AAAARRRRGGGGUUUUMMMMEEEENNNNTTTTSSSS
  47.      JOB     (input) CHARACTER*1
  48.              = 'E': compute only ALPHA and BETA.  A and B will not necessarily
  49.              be put into generalized Schur form.  = 'S': put A and B into
  50.              generalized Schur form, as well as computing ALPHA and BETA.
  51.  
  52.      COMPQ   (input) CHARACTER*1
  53.              = 'N': do not modify Q.
  54.              = 'V': multiply the array Q on the right by the conjugate
  55.              transpose of the unitary tranformation that is applied to the
  56.              left side of A and B to reduce them to Schur form.  = 'I': like
  57.              COMPQ='V', except that Q will be initialized to the identity
  58.              first.
  59.  
  60.  
  61.  
  62.  
  63.                                                                         PPPPaaaaggggeeee 1111
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70. ZZZZHHHHGGGGEEEEQQQQZZZZ((((3333FFFF))))                                                          ZZZZHHHHGGGGEEEEQQQQZZZZ((((3333FFFF))))
  71.  
  72.  
  73.  
  74.      COMPZ   (input) CHARACTER*1
  75.              = 'N': do not modify Z.
  76.              = 'V': multiply the array Z on the right by the unitary
  77.              tranformation that is applied to the right side of A and B to
  78.              reduce them to Schur form.  = 'I': like COMPZ='V', except that Z
  79.              will be initialized to the identity first.
  80.  
  81.      N       (input) INTEGER
  82.              The order of the matrices A, B, Q, and Z.  N >= 0.
  83.  
  84.      ILO     (input) INTEGER
  85.              IHI     (input) INTEGER It is assumed that A is already upper
  86.              triangular in rows and columns 1:ILO-1 and IHI+1:N.  1 <= ILO <=
  87.              IHI <= N, if N > 0; ILO=1 and IHI=0, if N=0.
  88.  
  89.      A       (input/output) COMPLEX*16 array, dimension (LDA, N)
  90.              On entry, the N-by-N upper Hessenberg matrix A.  Elements below
  91.              the subdiagonal must be zero.  If JOB='S', then on exit A and B
  92.              will have been simultaneously reduced to upper triangular form.
  93.              If JOB='E', then on exit A will have been destroyed.
  94.  
  95.      LDA     (input) INTEGER
  96.              The leading dimension of the array A.  LDA >= max( 1, N ).
  97.  
  98.      B       (input/output) COMPLEX*16 array, dimension (LDB, N)
  99.              On entry, the N-by-N upper triangular matrix B.  Elements below
  100.              the diagonal must be zero.  If JOB='S', then on exit A and B will
  101.              have been simultaneously reduced to upper triangular form.  If
  102.              JOB='E', then on exit B will have been destroyed.
  103.  
  104.      LDB     (input) INTEGER
  105.              The leading dimension of the array B.  LDB >= max( 1, N ).
  106.  
  107.      ALPHA   (output) COMPLEX*16 array, dimension (N)
  108.              The diagonal elements of A when the pair (A,B) has been reduced
  109.              to Schur form.  ALPHA(i)/BETA(i) i=1,...,N are the generalized
  110.              eigenvalues.
  111.  
  112.      BETA    (output) COMPLEX*16 array, dimension (N)
  113.              The diagonal elements of B when the pair (A,B) has been reduced
  114.              to Schur form.  ALPHA(i)/BETA(i) i=1,...,N are the generalized
  115.              eigenvalues.  A and B are normalized so that BETA(1),...,BETA(N)
  116.              are non-negative real numbers.
  117.  
  118.      Q       (input/output) COMPLEX*16 array, dimension (LDQ, N)
  119.              If COMPQ='N', then Q will not be referenced.  If COMPQ='V' or
  120.              'I', then the conjugate transpose of the unitary transformations
  121.              which are applied to A and B on the left will be applied to the
  122.              array Q on the right.
  123.  
  124.  
  125.  
  126.  
  127.  
  128.  
  129.                                                                         PPPPaaaaggggeeee 2222
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136. ZZZZHHHHGGGGEEEEQQQQZZZZ((((3333FFFF))))                                                          ZZZZHHHHGGGGEEEEQQQQZZZZ((((3333FFFF))))
  137.  
  138.  
  139.  
  140.      LDQ     (input) INTEGER
  141.              The leading dimension of the array Q.  LDQ >= 1.  If COMPQ='V' or
  142.              'I', then LDQ >= N.
  143.  
  144.      Z       (input/output) COMPLEX*16 array, dimension (LDZ, N)
  145.              If COMPZ='N', then Z will not be referenced.  If COMPZ='V' or
  146.              'I', then the unitary transformations which are applied to A and
  147.              B on the right will be applied to the array Z on the right.
  148.  
  149.      LDZ     (input) INTEGER
  150.              The leading dimension of the array Z.  LDZ >= 1.  If COMPZ='V' or
  151.              'I', then LDZ >= N.
  152.  
  153.      WORK    (workspace/output) COMPLEX*16 array, dimension (LWORK)
  154.              On exit, if INFO >= 0, WORK(1) returns the optimal LWORK.
  155.  
  156.      LWORK   (input) INTEGER
  157.              The dimension of the array WORK.  LWORK >= max(1,N).
  158.  
  159.      RWORK   (workspace) DOUBLE PRECISION array, dimension (N)
  160.  
  161.      INFO    (output) INTEGER
  162.              = 0: successful exit
  163.              < 0: if INFO = -i, the i-th argument had an illegal value
  164.              = 1,...,N: the QZ iteration did not converge.  (A,B) is not in
  165.              Schur form, but ALPHA(i) and BETA(i), i=INFO+1,...,N should be
  166.              correct.  = N+1,...,2*N: the shift calculation failed.  (A,B) is
  167.              not in Schur form, but ALPHA(i) and BETA(i), i=INFO-N+1,...,N
  168.              should be correct.  > 2*N:     various "impossible" errors.
  169.  
  170. FFFFUUUURRRRTTTTHHHHEEEERRRR DDDDEEEETTTTAAAAIIIILLLLSSSS
  171.      We assume that complex ABS works as long as its value is less than
  172.      overflow.
  173.  
  174.  
  175.  
  176.  
  177.  
  178.  
  179.  
  180.  
  181.  
  182.  
  183.  
  184.  
  185.  
  186.  
  187.  
  188.  
  189.  
  190.  
  191.  
  192.  
  193.  
  194.  
  195.                                                                         PPPPaaaaggggeeee 3333
  196.  
  197.  
  198.  
  199.